'\" t
.TH "ORG\&.FREEDESKTOP\&.TIMEDATE1" "5" "" "systemd 256.7" "org.freedesktop.timedate1"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
org.freedesktop.timedate1 \- The D\-Bus interface of systemd\-timedated
.SH "INTRODUCTION"
.PP
\fBsystemd-timedated.service\fR(8)
is a system service that can be used to control the system time and related settings\&. This page describes the D\-Bus interface\&.
.SH "THE D\-BUS API"
.PP
The service exposes the following interfaces on the bus:
.sp
.if n \{\
.RS 4
.\}
.nf
node /org/freedesktop/timedate1 {
  interface org\&.freedesktop\&.timedate1 {
    methods:
      SetTime(in  x usec_utc,
              in  b relative,
              in  b interactive);
      SetTimezone(in  s timezone,
                  in  b interactive);
      SetLocalRTC(in  b local_rtc,
                  in  b fix_system,
                  in  b interactive);
      SetNTP(in  b use_ntp,
             in  b interactive);
      ListTimezones(out as timezones);
    properties:
      readonly s Timezone = \*(Aq\&.\&.\&.\*(Aq;
      readonly b LocalRTC = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly b CanNTP = \&.\&.\&.;
      readonly b NTP = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly b NTPSynchronized = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly t TimeUSec = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly t RTCTimeUSec = \&.\&.\&.;
  };
  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
};
    
.fi
.if n \{\
.RE
.\}













.SS "Methods"
.PP
Use
\fBSetTime()\fR
to change the system clock\&. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC)\&. If
\fIrelative\fR
is true, the passed usec value will be added to the current system time\&. If it is false, the current system time will be set to the passed usec value\&. If the system time is set with this method, the RTC will be updated as well\&.
.PP
Use
\fBSetTimezone()\fR
to set the system timezone\&. Pass a value like
"Europe/Berlin"
to set the timezone\&. Valid timezones are listed in
/usr/share/zoneinfo/zone\&.tab\&. If the RTC is configured to be maintained in local time, it will be updated accordingly\&.
.PP
Use
\fBSetLocalRTC()\fR
to control whether the RTC is in local time or UTC\&. It is strongly recommended to maintain the RTC in UTC\&. However, some OSes (Windows) maintain the RTC in local time, which might make it necessary to enable this feature\&. Note that this might create various problems as daylight changes could be missed\&. If
\fIfix_system\fR
is
"true", the time from the RTC is read again and the system clock is adjusted according to the new setting\&. If
\fIfix_system\fR
is
"false", the system time is written to the RTC taking the new setting into account\&. Use
\fIfix_system=true\fR
in installers and livecds where the RTC is probably more reliable than the system time\&. Use
\fIfix_system=false\fR
in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC\&.
.PP
Use
\fBSetNTP()\fR
to control whether the system clock is synchronized with the network using
systemd\-timesyncd\&. This will enable and start or disable and stop the chosen time synchronization service\&.
.PP
\fBListTimezones()\fR
returns a list of time zones known on the local system as an array of names ("["Africa/Abidjan", "Africa/Accra", \&.\&.\&., "UTC"]")\&.
.SS "Properties"
.PP
\fITimezone\fR
shows the currently configured time zone\&.
\fILocalRTC\fR
shows whether the RTC is configured to use UTC (false), or the local time zone (true)\&.
\fICanNTP\fR
shows whether a service to perform time synchronization over the network is available, and
\fINTP\fR
shows whether such a service is enabled\&.
.PP
\fINTPSynchronized\fR
shows whether the kernel reports the time as synchronized (c\&.f\&.
\fBadjtimex\fR(3))\&.
\fITimeUSec\fR
and
\fIRTCTimeUSec\fR
show the current time on the system and in the RTC\&. The purpose of those three properties is to allow remote clients to access this information over D\-Bus\&. Local clients can access the information directly\&.
.PP
Whenever the
\fITimezone\fR
and
\fILocalRTC\fR
settings are changed via the daemon,
\fBPropertyChanged\fR
signals are sent out to which clients can subscribe\&.
.PP
Note that this service will not inform you about system time changes\&. Use
\fBtimerfd\fR(3)
with
\fBCLOCK_REALTIME\fR
and
\fBTFD_TIMER_CANCEL_ON_SET\fR
for that\&.
.SS "Security"
.PP
The
\fIinteractive\fR
boolean parameters can be used to control whether
\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2
should interactively ask the user for authentication credentials if required\&.
.PP
The polkit action for
\fBSetTimezone()\fR
is
org\&.freedesktop\&.timedate1\&.set\-timezone\&. For
\fBSetLocalRTC()\fR
it is
org\&.freedesktop\&.timedate1\&.set\-local\-rtc, for
\fBSetTime()\fR
it is
org\&.freedesktop\&.timedate1\&.set\-time
and for
\fBSetNTP()\fR
it is
org\&.freedesktop\&.timedate1\&.set\-ntp\&.
\fBListTimezones()\fR
does not require any privileges\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.timedate1 on the bus\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
  \-\-dest org\&.freedesktop\&.timedate1 \e
  \-\-object\-path /org/freedesktop/timedate1
      
.fi
.if n \{\
.RE
.\}
.SH "VERSIONING"
.PP
These D\-Bus interfaces follow
\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBMore information on how the system clock and RTC interact\fR\m[]\&\s-2\u[3]\d\s+2
.SH "NOTES"
.IP " 1." 4
polkit
.RS 4
\%https://www.freedesktop.org/software/polkit/docs/latest/
.RE
.IP " 2." 4
the usual interface versioning guidelines
.RS 4
\%https://0pointer.de/blog/projects/versioning-dbus.html
.RE
.IP " 3." 4
More information on how the system clock and RTC interact
.RS 4
\%https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html
.RE
